2 LUA API回调函数说明
概述
本文将介绍大彩LUA脚本API函数中的回调函数使用方法，以及调用回调函数的注意事项，介绍常见的api回调接口，如下所示
- 初始化函数：on_init()
- 系统滴答1s回调函数：on_systick()
- 控件触发回调函数：on_control_notify(screen, control, value)
- 切换画面回调函数：on_screen_change(screen)
- 定时器超时回调函数：on_timer(timer_id)
- 画图/线/几何图形回调函数：on_draw(screen)
- U盘、SD卡的回调函数：on_usb_inserted(dir)/on_usb_removed()/on_sd_inserted(dir)/on_sd_removed()
注：更多LUA资料可参考LUA 脚本API函数接口 章节 和网站：www.runoob.com/lua
适用范围：M系列、W系列、X系列、F系列（固件版本 >= V4.2.401.0）
例程下载链接：《LUA API 回调函数说明》(点击跳转)
注意事项
- 大彩lua api里的回调函数不可以被其他函数调用，属于被动触发，自动回调，如用户对文本控件键值输入，触发回调函数on_control_notify(screen, control, value)
- 不能更改回调函数的函数名、参数等
1.1 函数 on_init()
系统上电加载 LUA 脚本文件之后，立即调用此回调函数， 通常用于执行初始化操作，仅执行一次
画面配置
在画面中添加两个文本控件，ID1用于显示电压值，ID2用于显示电流，如下所示
LUA脚本
在on_init（）函数中填写设置文本框数值的API函数，在系统初始化时调用执行。具体代码下所示
--[[***************************************************************************
** Function name: on_init（）
** Descriptions: 系统初始化时，执行此回调函数。
注意：回调函数的参数和函数名固定不能修改
***************************************************************************--]]
function on_init( )
set_value(1,1,10) --设置文本控件的值
set_value(1,2,2) --设置文本控件的值
end
运行预览
运行虚拟屏，该画面的电压值为10，电流值为2，如下所示，用户可以通过lua脚本修改对应的值，进一步熟悉了解
1.2 函数on_systick()
系统每隔 1 秒钟自动调用此回调函数
画面配置
该画面添加一个文本控件，用于累计on_systick（）被触发回调的次数
LUA脚本
教程中在on_systick（）函数里添加了一个显示回调函数被执行次数的程序，具体代码如下所示
--[[***************************************************************************
** Function name: on_systick
** Descriptions: 定时回调函数，系统每隔1秒钟自动调用。
注意：回调函数的参数和函数名固定不能修改
***************************************************************************--]]
function on_systick( )
sys_timer = sys_timer +1
set_value(2,1,sys_timer)
end
运行预览
每秒触发on_systick（）函数，效果如下所示
1.3 函数on_timer(timer_id)
on_timer(timer_id)定时器超时回调函数，单独使用不生效。该函数触发回调需要配合 start_timer(timer_id, timeout, countdown, repeat) ，来开启定时器，定时器溢出超时了，才会触发on_timer(timer_id)
画面配置
画面中放置了两个按钮，一个启用定时器，一个停止定时器和一个文本框，文本框是显示定时器超时后调用的次数，如下所示
LUA脚本
教程中在on_timer （）函数里添加了一个显示回调函数被执行次数的程序，具体代码如下所示
--[[***************************************************************************
** Function name: on_timer
** Descriptions: 定时器超时，执行此回调函数
注意：回调函数的参数和函数名固定不能修改
** Input value : timer_id 定时超时的定时器ID号，定时器编号0~31
***************************************************************************--]]
function on_timer(timer_id)
--定时器0超时触发
if timer_id == 0
then
timer_out = timer_out +1
set_value(3,3,timer_out)
end
end
--[[***************************************************************************
** Function name: on_control_notify
** Descriptions: 用户通过触摸修改控件后，执行此回调函数。
点击按钮控件，修改文本控件、修改滑动条都会触发此事件。
注意：回调函数的参数和函数名固定不能修改
** Input value : screen 画面ID
control 控件ID
value 控件值(包括文本控件输入的值)
***************************************************************************--]]
function on_control_notify(screen,control,value)
--***********************************************************
--功能：按下画面4的控件1启动定时器0
--调用函数：start_timer(timer_id, timeout, countdown, repeat)
--函数功能：启动定时器
--参数： timer_id， 定时器ID；
-- timeout， 超时时间；
-- countdown，1顺计时，0倒计时
-- repeat 计时次数，0无限循环
--***********************************************************
if screen == 3 and control == 1 and value == 1
then
start_timer(0,1000,1,0) --开启定时时器0工作，设置计时1秒触发一次on_timer
elseif screen == 3 and control == 2 and value == 1
then
stop_timer(0) --停止定时时器0工作
timer_out = 0
end
……
end
运行预览
开启定时器后，超时触发on_timer()，效果如下所示
1.4 函数on_control_notify(screen,control,value)
用户触摸修改控件后，执行此回调函数。点击按钮控件，修改文本控件、修改滑动条等等都会触发此函数，如果单片机串口指令修改控件值、脚本设置set_value或按钮对内置指令触发其他控件等均不会触发该回调函数，仅用户操作屏幕控件才会触发
PS：对按钮控件而言，设置了以下两个配置其中一个，按钮控件均不会触发on_control_notify( )
1.对应单个按钮控件，若设置【事件通知】为否，该按钮控件按下时候，就不会触发on_control_notify( )，如下所示
2.工程属性配置，全局配置按钮属性【按钮事件通知】处，如下所示
- 若设置为”关闭“：所有按钮控件均不会触发
- 若设置为”仅按下时“：所有按钮控件均仅按下时候触发
- 若设置为”仅弹起时“：所有按钮控件均仅弹起时候触发
- 若设置为”按下和弹起时“：所有按钮控件按下和弹起时都会触发
画面配置
画面中放置常见的控件做示例，如添加1个按钮控件(ID1)、1个文本控件（ID2，键盘输入）、1个图标控件（ID3，允许触摸）、1个滑动选择控件（ID4）、1个菜单控件（ID5）、1个滑动选择控件（ID6）。在增加一个文本控件（ID7），用于记录哪个控件触发，如下所示
LUA脚本
本章节，在回调函数显示触发on_control_notify对应的控件，将按下的信息显示到文本控件ID7中，具体代码如下所示
--[[***************************************************************************
** Function name: on_control_notify
** Descriptions : 用户通过触摸修改控件后，执行此回调函数。
点击按钮控件，修改文本控件、修改滑动条都会触发此事件。
注意：回调函数的参数和函数名固定不能修改
** Input value : screen 画面ID
control 控件ID
value 控件值(包括文本控件输入的值)
***************************************************************************--]]
function on_control_notify(screen,control,value)
--***********************************************************
--功能：按下画面4的控件1启动定时器0
--调用函数：start_timer(timer_id, timeout, countdown, repeat)
--函数功能：启动定时器
--参数： timer_id， 定时器ID；
-- timeout， 超时时间；
-- countdown，1顺计时，0倒计时
-- repeat 计时次数，0无限循环
--***********************************************************
……
if screen == 4
then
if control == 1 and value == 1 --value == 1 按钮按下
then
set_text(4,7,"按钮按下")
elseif control == 1 and value == 0 --value == 0 按钮弹起
then
set_text(4,7,"按钮弹起")
elseif control == 2 --文本输入
then
set_text(4,7,"文本输入")
elseif control == 3 --图标控件
then
set_text(4,7,"触摸图标")
elseif control == 4 --滑动选择控件
then
set_text(4,7,"滑动选择")
elseif control == 5 --菜单控件
then
set_text(4,7,"菜单选择")
elseif control == 6 --滑块控件
then
set_text(4,7,"滑块滑动")
end
end
……
end
运行预览
依次点击控件ID1~ID6，效果如下所示
1.5 函数on_screen_change(screen)
当画面切换后，执行此回调函数
- screen：画面切换后的目标画面ID。假设画面A切换到画面B，这个动作完成后，则screen为画面B的‘画面ID’值
注意：在on_screen_change(screen)里调用change_screen切换画面，不会在触发on_screen_change
画面配置
本文按钮控件的属性设置为画面切换，点击该按钮控件就会将画面切换到指定的画面中，如下所示
测试画面中，添加两个文本控件，在脚本触发回调函数on_screen_change时，设置控件ID1显示当前画面的ID，控件ID2显示数值，配置如下所示
LUA脚本
屏在切换画面的同时会触发回调函数on_screen_change，从而实现在切换画面是将目标画面的两个文本控件进行修改，具体代码如下所示
--[[***************************************************************************
** Function name: on_screen_change
** Descriptions: 当画面切换至目标画面ID时，执行此回调函数
注意：回调函数的参数和函数名固定不能修改
** Input value : screen 目标画面ID
*******************************************************************************--]]
function on_screen_change(screen)
if screen == 8 then --切换到画面9时，修改控件1，2的数据
set_value(8,1,screen) --修改控件1的数据
set_value(8,2,30) --修改控件2的数据
end
end
运行预览
触发on_screen_change，效果如下所示
1.6 函数on_draw()
重绘时执行此回调函数，通常所有绘图、画几何（圆、矩形、线、点等等）操作都在此函数中实现。当画面的控件刷新的时候，也会触发此函数，一般搭配redraw ( ) 使用。
- screen ：需要画图的画面ID
画面配置
在该画面添加两个按钮控件，分别按下时候，显示不同的图片
LUA脚本
在LUA本按钮按下时，给show_picture赋不一样的值，在调用redraw() 触发回调函数on_draw()，来显示指定的图片
--[[***************************************************************************
** Function name: on_draw
** Descriptions : 画面刷新时，或者使用API函数 redraw 申请重绘，执行此回调函数
注意：回调函数的参数和函数名固定不能修改
** Input value : screen 目标画面ID
***************************************************************************--]]
function on_draw(screen)
--******************************************************************************
--调用函数：draw_image(image_id,frame_id,dstx,dsty,width,height,srcx,srcy)
--函数功能：根据图片ID绘图
--参数： image_id 图片资源的 ID
--frame_id 对应图标， 可以设置帧 ID，其他图片固定为 0
--dstx 图片显示 X 坐标
--dsty 图片显示 Y 坐标
--width 图片显示宽度
--height 图片显示高度
--srcx 图片裁剪 X 坐标
--srcy 图片裁剪 Y 坐标
--*****************************************************************************
if screen == 6 and show_picture == 1
then
draw_image(23,0,190,160,430,230,0,0)
elseif screen == 6 and show_picture == 2
then
draw_image(24,0,190,160,430,230,0,0)
end
end
function on_control_notify(screen,control,value)
if screen == 5
then
if control == 1 and value == 1 --绘制图片1
then
show_picture = 1
redraw() --申请重绘
elseif control == 2 and value == 1 --绘制图片2
then
show_picture = 2
redraw() --申请重绘
end
end
end
运行预览
绘图效果如下所示
1.7 U盘/SD卡回调函数
当插入U盘和SD卡插入时，触发on_usb_inserted(dir)或on_sd_inserted(dir)函数。若拔掉U盘和SD卡插入时，触发on_usb_removed()或on_sd_removed()函数
- dir: 该参数表示U盘或SD卡的盘符
注意：具体是SD还是U盘，以实体屏为准，且测试体验API，请在实体屏上测试
工程配置
画面中，添加两个文本控件，控件ID1用于显示U盘触发的相关信息，控件ID2用于显示SD卡触发的相关信息，如下所示
LUA脚本
U盘/SD卡插入及拔出时的LUA脚本代码如下所示
--[[***************************************************************************
** Function name: on_usb_inserted
** Descriptions : 插入U盘后，执行此回调函数
注意：回调函数的参数和函数名固定不能修改
** Input value : dir U盘的路径
***************************************************************************--]]
function on_usb_inserted(dir)
set_text(7,1,dir) --显示U盘路径
end
--[[***************************************************************************
** Function name: on_sd_inserted
** Descriptions : 插入SD卡后，执行此回调函数
注意：回调函数的参数和函数名固定不能修改
** Input value : dir SD卡的路径
***************************************************************************--]]
function on_sd_inserted(dir)
set_text(7,2,dir) --显示SD卡路径
end
--[[***************************************************************************
** Function name: on_sd_inserted
** Descriptions : 拔出U盘后，执行此回调函数
注意：回调函数的参数和函数名固定不能修改
***************************************************************************--]]
function on_usb_removed()
set_text(7,1,"已拔出U盘")
end
--[[***************************************************************************
** Function name: on_sd_inserted
** Descriptions : 拔出SD卡后，执行此回调函数
注意：回调函数的参数和函数名固定不能修改
***************************************************************************--]]
function on_sd_removed()
set_text(7,2,"已拔出SD卡")
end